FAQ

This page collects the most common V3 integration questions. The V3 Error Codes page answers most failure scenarios; this page focuses on why the API works this way, how to fix the request, and what changed when migrating from V1/V2.

Credentials and authentication

1. How do I become a developer and create an AccessKey?

Account registration and credential application are identical across all API versions. The full flow lives in Quick Start:

1. Invite or register a Gausium developer: invite within your organization, or have an admin manage other organizations in the IAM customer center.
2. Activate the developer account: complete activation from the email.
3. Create an AccessKey in My AccessKeys in the Developer Center, which issues AccessKeyID, AccessKeySecret, ClientID, and ClientSecret together.

Application Management is retired

The old Application Management page is no longer used to create applications. Creating an AccessKey generates the application information automatically.

2. Can I call V3 APIs with a V1 AccessKey?

Yes. A V1 AccessKey can be upgraded to V3 in the Developer Center, but ClientID stays empty after the upgrade, so keep using the ClientID from the original application. Only a newly created V3 AccessKey issues all four credentials together: AccessKeyID, AccessKeySecret, ClientID, and ClientSecret.

3. How long does access_token last? Do I need a new one before every call?

It lasts 24 hours by default. Do not fetch a new token before every business call; refresh before expiry based on expires_in. Once expired, call Refresh OAuth Token with the refresh_token instead of re-authorizing.

4. I keep getting 110002 even though I just got a token.

Check in this order:

1. Is the Authorization value exactly Bearer {access_token} with a single space?
2. Did you use AccessKeySecret as the access_token? They are not interchangeable.
3. Was the token issued for the current environment? A test-environment token cannot call production.
4. Is a gateway or proxy rewriting the Authorization header?

5. I get 110003 even though the token is valid.

110003 means authentication succeeded but you lack resource permission. The usual cause is that the robotSn in the request is not bound to your account. Use List Robots to confirm the robot is inside your account's authorized scope.

6. Can I recover a lost AccessKeySecret?

The plaintext is never shown again, but you can regain access: use Download Secret on that entry in My AccessKeys, or Update Secret to generate a new one. After an update the old secret stops working immediately, so update your server configuration as well.

Requests and responses

7. The HTTP status is 200 but the call clearly failed.

That is the V3 convention. Business errors always return HTTP 200; the real outcome is in the response body's code. Always parse code: only code = 0 is success. Non-200 HTTP statuses only appear when the gateway rejects the request.

8. I get 100003 but msg does not say which field is wrong.

msg is a human-readable English hint and is not guaranteed to name the field. Check in order:

1. Are all required fields present, with exactly matching names and casing?
2. Do enum fields use values listed on the endpoint page?
3. Does any array exceed the per-request limit documented on the page?
4. Did you send a number as a string?

9. What should I do about 100026 rate limiting?

Lower concurrency and retry with exponential backoff rather than retrying immediately at the same rate. For batch workloads, serialize or split the calls.

10. What should I include when reporting a problem?

At minimum: the traceId, the endpoint path, the request time (to the minute), and the request body (with secrets removed). The traceId maps directly to cloud logs and is far more useful than a screenshot.

11. What is the pagination limit? Is the V1/V2 value of 200 still valid?

No. The V3 per-page limit is 100, not the legacy 200. Common values:

Scenario	Limit
pageSize on V3 paginated endpoints	1 ~ 100
robotSnList on the status snapshot	At most 100 robots per call
robotSnList filters on list endpoints	At most 100 robots per call

Exceeding a limit usually returns 100003.

12. Why do some endpoints use pageNumber while others use page?

Most V3 paginated endpoints use pageNumber / pageSize, but the task report endpoint keeps the legacy page / pagesize naming (all lowercase). This is historical field compatibility, not a documentation typo. Follow each endpoint's field table and do not copy naming across endpoints.

13. What is the V3 API host?

V3 endpoints all start with /openapi/v3/, and the host differs per environment. Use the host shown in each endpoint page's curl example.

The V1/V2 host https://openapi.gs-robot.com/ cannot simply have its path replaced with V3 paths; they are different services.

Robots and status

14. Is the status snapshot real-time?

No. Status data is not updated in real time; the maximum delay is about 30 seconds. Do not use snapshot coordinates for real-time obstacle avoidance or safety decisions, and do not send commands based on stale status.

If the business needs stronger certainty (for example, confirming a task has finished before dispatching the next one), widen the wait window to 60 seconds and cross-check the task state.

15. Should I fetch the robot status before controlling it?

Yes. Fetch the current status first and base the command on the latest data. Sending a command based on a status from two hours ago is unsafe: the robot may have moved or changed state.

16. Why are status fields missing and coordinates 0 while the robot is offline?

While offline, runtime fields such as battery, current task, map, and position may be missing or fall back to documented defaults. Coordinates are only populated when all three conditions hold: localization is complete, a valid grid coordinate exists, and map metadata is complete. A coordinate of 0 does not mean the robot is at the origin; never use it to correct the robot position.

17. What is workState? Why is there no V1-style taskState?

The V3 status snapshot returns workState, the raw robot work-state code passed through without cloud-side re-interpretation, and only when the robot is online.

The V1 taskState values (idle / running / paused / other) are not part of the V3 contract and cannot be mapped onto V3 fields. To decide whether a task is running, combine taskInstanceId, taskName, and the task report endpoints instead.

18. How do I read angle, gridPosition, and worldPosition?

They describe the same position in three forms:

Field	Meaning
position.angle	Robot heading in degrees.
position.gridPosition	Grid coordinate x / y, integer cells.
position.worldPosition.position	World coordinate x / y / z, floats, unit tied to the map resolution.
position.mapInfo	Map metadata: gridWidth, gridHeight, originX, originY, resolution.

Converting grid coordinates to world coordinates requires both the origin and the resolution from mapInfo; gridPosition alone cannot reconstruct the real position.

19. I get 210002 robot offline.

That command requires the robot to be online. Wait for it to reconnect, or confirm its online state with the status snapshot before dispatching.

20. I get 210000 unsupported.

The robot has not declared support for the target task or command. The usual cause is a model capability mismatch or a software version below AIO 1.6. V3 APIs only guarantee compatibility with AIO 1.6 and later. Use Get Robot Combined Task Capabilities to confirm what the robot actually supports.

21. How do I know which floor the robot is on when elevator control is deployed?

V3 has no dedicated floor field. The common approach is to encode the building and floor in the map name and infer the floor from currentMapName / currentMapId in the status snapshot. Establish a consistent map naming convention instead of maintaining a floor mapping table on the integration side.

22. How do I tell whether a robot belongs to the M line or the S line?

Check modelFamilyCode:

modelFamilyCode	Line
s, sw	S line
40, 50, omine	M line
75	L line, driven through the M line interface behavior

V3 no longer requires choosing a different endpoint per line: one set of endpoints serves all robot families, and modelFamilyCode only tells you about capability differences (supported work modes, subtask types). Treat unknown families as the S line.

23. Can I dispatch commands while the robot is charging or in low power?

It depends on the command type:

• Control commands (navigation, pause, resume, stop): not executable while the robot is docked and charging. Undock the robot first.
• Cleaning tasks: can be created while charging as long as the battery is not low; the robot executes when conditions allow. A low battery should be charged first.

Low power mode does not prevent the robot from receiving commands, but actual execution still depends on battery level and task state.

24. Where do the valid cleaningMode values come from?

Do not hard-code an enum. Read the robot's reported capabilities: call Query robot work modes with robotSn, then combine the returned mode, strength, subType and type into the task work mode.

cleaningMode in a task report is the work mode actually used at execution time. Use it for review only; do not infer the valid range from it.

25. How often does the robot report its position?

Roughly once per second while moving and once every three seconds while idle. The status snapshot endpoint does not update at that rate: it aggregates at a lower frequency with up to about 30 seconds of delay. For near real-time tracking, do not rely on polling the snapshot.

Maps

26. Which value should I send as mapId?

Send the map's localMapUuid. If you get 230010, the mapId you sent is not the localMapUuid, or the two differ. Use List Robot Maps to obtain the correct identifier.

27. I get 220002 map resource not part of the map.

Partitions, paths, and positions must all come from the same map. Mixing resources across maps triggers this error. Confirm that the map identifier in the resource query result matches the request.

28. I only get auto-partitioned regions. Where are my manually drawn areas?

V3 region queries return auto-partitioned regions. Areas drawn by hand in the console are not regions; they appear as paths in map resources. Call List schedule map resources and read data.maps[].paths.

To execute against a drawn area, express it through a schedule plan instead of dispatching a temporary task by region.

29. Why are the map coordinates or the map canvas empty?

Map path and coordinate data depends on the robot proactively reporting it to the cloud. Older software versions do not provide that reporting path, so only map metadata (size, resolution) is returned and paths / regions or the canvas stay empty.

Confirm whether the robot software version supports reporting. If it does not, the robot must be upgraded; this is not a parameter problem and cannot be fixed by changing the request.

Tasks and schedules

30. Which V3 endpoint dispatches a task?

V3 splits endpoints by task type instead of using one generic command endpoint:

Scenario	Endpoint
Run a one-off combined task	Start Combined Task
Run a saved persistent combined task definition	Maintain it under task definitions first, then start it
Run on a calendar recurrence	Standard schedule or simple schedule
Navigate / pause / resume / stop	Command operations

The V1 approach of picking a different path by model and software version no longer applies; choose by task type.

31. I created a combined task successfully, but the robot did not move.

Creating a combined task only saves the task definition; it does not run anything. Call Start Combined Task next, and keep the returned requestId to track execution.

32. I get 230014 or 230015.

230014 means the task runtime or task item does not exist, typically because a finished taskId is being reused. 230015 means the task state does not allow the command, or the task version has changed. Query the task state again before deciding the next step instead of blindly retrying the same command.

33. I get 230013 schedule start date earlier than today.

Schedules cannot start in the past. Move the start date to today or later. In cross-timezone deployments, remember that the submitted time is interpreted in the site's timezone.

34. I get 230019 charging position not specified.

The map has multiple charging positions and the request did not choose one. Call List Charging Positions first, then include the specific position in the request.

35. Task startup fails with a 10-digit code such as 20101000xx.

That is a robot-side business code, not a six-digit cloud code. Look it up in Task Startup Failure Error Codes. The outer cloud code always follows the V3 numbering rules.

36. What happens if I dispatch a task while the robot is already running one?

V3 has no task queue. A robot runs only one task at a time, and a conflicting new task returns 230015 (task state or version conflict) instead of waiting for the current task to finish.

The order is fixed: stop the current task, confirm the result, then dispatch the new task. Whether a higher-priority task may replace the running one depends on the robot software version; do not design business flows that rely on it.

37. What conditions does cross-map navigation require?

All three must hold: the target map is connected to the current map, both belong to the same site, and the site has elevator control bound. If any condition is missing, the command may be accepted but fail during execution.

Before dispatching, confirm mapId with List robot maps and verify how the maps are connected.

Task reports

38. Does V3 support querying task reports by time range?

Yes. This is an improvement over V1/V2, which did not support time-range queries. Page Task Reports accepts endTimeMin and endTimeMax and filters by task end time.

Two caveats:

1. The format is yyyy-MM-dd HH:mm:ss and the value is robot local time, not UTC.
2. robotSn is required, so one request cannot aggregate across robots.

39. Why is today's task report missing?

Task reports require the robot to be online. If its network is poor or it is offline, the report may not arrive the same day. For example, a task on June 1 uploaded on June 2 will only be queryable after June 2.

Troubleshooting order: confirm the robot is online, re-query with a wider range, then confirm you used robot local time.

40. How do I fetch the map image of a task report?

First get the task report identifier with Page Task Reports, then fetch the image with Query Task Report Map Images.

The V1 GenerateRobotTaskReportPng and ListRobotTaskReports belong to a different API family; do not mix them with V3. languageCode expects an IETF language tag such as zh-CN or en-US.

41. Is durationSeconds = 0 a calculation bug?

No. startTime and endTime describe the task interval, while durationSeconds only counts time spent actually working. If the task did no real work because of a low battery, recharging or site obstruction, durationSeconds can be 0 even when the interval spans ten or more minutes.

Judge whether work happened by completionPercentage, actualCleaningAreaSquareMeter and areaNameList, not by the time difference alone.

42. Why is taskId or planId missing from a task report?

That is expected. Neither field is reported by every family and version:

• taskId: only some AIO versions (40 / 50 / S series) report it.
• planId: additionally requires the task to be triggered by a schedule plan. Temporary tasks have no planId.

When they are missing, use id as the unique report identifier and taskInstanceId to correlate the same execution instance.

43. What format do task report time fields use?

The query endpoint and the push endpoint differ, which is the most common trap:

Source	Format
Page task reports	startTime / endTime in the response are Unix seconds (e.g. 1785722400); the endTimeMin / endTimeMax query parameters use yyyy-MM-dd HH:mm:ss in robot local time
Task report push	startTime / endTime are Unix milliseconds (e.g. 1714124784000)

Passing a millisecond push value as seconds to the query endpoint lands far in the future and returns nothing. Normalize units before comparing across endpoints.

The complete field list for the push side is in Task Report Push.

Event push and callbacks

44. How do I tell whether a fault has been resolved?

Correlate alarms and recoveries by incidentId, and use incidentStatus for the state:

Field	How to read it
incidentId	The alarm and the recovery of the same fault share the same ID. A repeated fault creates a new incidentId instead of reusing the old one
incidentStatus	1 alarm, 0 recovery
endTime	Empty string while the fault is unresolved

Boundary cases you must handle:

1. Out-of-order delivery: pushes are concurrent, so a recovery can arrive before its alarm. After a recovery for an incidentId has been processed, ignore later alarms with the same ID; sorting by startTime also works as a fallback.
2. H0 has no recovery: H0 is a one-off event notification with no start / end state, so do not wait for its recovery.
3. Messages can be lost: a failed push is retried at most three times and is not sent again after success. A lost recovery leaves your system believing the fault persists, so periodically review faults that have stayed open unusually long.
4. Meaning of recovery: incidentStatus = 0 may mean self-recovery or on-site handling; it does not tell you which.

Field definitions, push format and signature verification are documented in Incident Push and Callback Signature.

45. Which incident levels are pushed?

incidentLevel determines external visibility:

Level	Meaning	Visible externally
H0	Event notification (not an alarm)	Yes, one-off message, no recovery event
H1	Telemetry	Yes
H2	Normal state	No, if it recovers within one minute
H4	Assistance / problem	No, if it recovers within one minute
H5	Risk	Yes
H6	Fault	No, if it recovers within one minute

The customer must also have an alarm template configured, and the event filter frequency setting applies. When a push seems missing, check the level, the template and the filter configuration before concluding that a message was lost.

The full definition of each level is in the payload.content.incidentLevel table of Incident Push.

Command operations

46. cmdStatus = 6 with cmdResultCode = 6880 means the task is done, right?

No. cmdStatus = 6 always returns 6880 and success, which only means the command was dispatched successfully. It does not mean the robot finished the action. Confirm the outcome by querying the task state or the robot status snapshot.

47. How do I avoid dispatching a command twice?

Write-command endpoints accept an optional Idempotency-Key header. When provided, the server trims surrounding whitespace and limits it to 128 characters; retrying with the same key reuses the existing command record instead of dispatching again. Include the same key when retrying after a timeout.

48. When can I query the result of a dispatched command?

Commands are asynchronous. After receiving the requestId, poll a single result with Get Command Status, or use List Command Records to review dispatch history in bulk.

Debugging and documentation

49. The API does not respond or returns no data. How do I troubleshoot?

Check in order:

1. Path: V3 business endpoints start with /openapi/v3/; do not reuse /openapi/v1alpha1/ and similar paths.
2. Method: V3 business endpoints use POST with a JSON body; GET is rejected at the gateway.
3. Host: are you using the current environment's host?
4. Auth: is Authorization: Bearer {access_token} correct?
5. Body: HTTP 200 can still be a business failure; always read code.

50. The online debugging panel fails with a CORS error.

Browsers enforce the same-origin policy, and some environments block cross-origin requests. This is browser behavior, not an API failure. Copy the generated curl command and run it in a terminal or on your server.

51. Is there a robot software version requirement for V3 APIs?

Yes. V3 APIs only guarantee compatibility with AIO 1.6 and later. Robots below that version should keep using V1/V2 APIs.

52. I cannot find the V3 equivalent of a V1 endpoint.

The V3 left navigation currently has seven groups: Authentication, Base Info, Command Operation, Map Data, Tasks and Scheduling, Robot Push Service, and Elevator Control System Interface Protocol. The last two are protocol and callback conventions rather than V3 REST endpoints, so they were carried over into the V3 navigation with unchanged content. The remaining V1/V2 REST endpoints are not all migrated yet; check the navigation by group, and keep using the legacy path for anything not covered.

Key differences from V1/V2

When migrating from V1/V2, these are the easiest traps:

Item	V1/V2	V3
Business error code	4/5 digits	Fixed 6 digits, see V3 Error Codes
Success check	Some endpoints use success	Only code = 0
Pagination limit	200	100
Task dispatch	Pick a different command path by model / version	Split by task type
Robot list scope	relation accepts contract / empty	No relation parameter; the default scope depends on the AccessKey version: V3 credentials default to current-user bindings, V1 credentials default to the end customer
Task state field	taskState with four semantic values	workState raw numeric passthrough
Task report time filter	Not supported	endTimeMin / endTimeMax supported
Task report pagination	page / pagesize	Most endpoints use pageNumber / pageSize; task reports still use page / pagesize

Pay special attention to the robot list scope: the Page Authorized Robots default scope is determined by the AccessKey version used to obtain the token:

• V3 AccessKey: defaults to robots directly bound to the current user.
• V1 AccessKey: defaults to robots of the customer as the end customer.

In other words, the same account calling the same endpoint with tokens from the two AccessKey versions can receive different robot lists. This is an authorization-scope semantic difference, not missing data. The V3 robot list does not accept a relation parameter; for contract-customer scope, keep using the legacy List Robots endpoint with relation=contract.